=begin pod

=TITLE enum Bool

=SUBTITLE Logical boolean

    enum Bool <False True>

X<|True>
X<|False>
X<|Boolean>
An enum for boolean true/false decisions.

=head1 Methods

=head2 routine succ

    method succ(--> Bool:D)

Returns C<True>.

    say True.succ;                                    # OUTPUT: «True␤»
    say False.succ;                                   # OUTPUT: «True␤»

C<succ> is short for "successor"; it returns the next enum value. Bool is a special enum with only two values, C<False> and C<True>. When sorted, C<False> comes first, so C<True> is its successor. And since C<True> is the "highest" Bool enum value, its own successor is also C<True>.

=head2 routine pred

    method pred(--> Bool:D)

Returns C<False>.

    say True.pred;                                    # OUTPUT: «False␤»
    say False.pred;                                   # OUTPUT: «False␤»

C<pred> is short for "predecessor"; it returns the previous enum value. Bool is a special enum with only two values, C<False> and C<True>. When sorted, C<False> comes first, so C<False> is the predecessor to C<True>. And since C<False> is the "lowest" Bool enum value, its own predecessor is also C<False>.

=head2 routine enums

    method enums(--> Hash:D)

Returns a L<Hash|/type/Hash> of enum-pairs. Works on both the C<Bool> type
and any key.

    say Bool.enums;                                   # OUTPUT: «{False => 0, True => 1}␤»
    say False.enums;                                  # OUTPUT: «{False => 0, True => 1}␤»

=head2 routine pick

    multi method pick(Bool:U --> Bool:D)
    multi method pick(Bool:U $count --> Seq:D)

Returns C<True> or C<False> if called without any argument. Otherwise returns
C<$count> elements chosen at random (without repetition) from the C<enum>. If
C<*> is passed as C<$count>, or C<$count> is greater than or equal to two, then
both elements are returned in random order.

    say Bool.pick;                                    # OUTPUT: «True␤»
    say Bool.pick(1);                                 # OUTPUT: «(False)␤»
    say Bool.pick(*);                                 # OUTPUT: «(False True)␤»

=head2 routine roll

    multi method roll(Bool:U --> Bool:D)
    multi method roll(Bool:U $count --> Seq:D)

Returns C<True> or C<False> if called without any argument. Otherwise returns
C<$count> elements chosen at random. Note that each random choice from the
C<enum> is made independently, like a separate coin toss where each side of the
coin represents one of the two values of the C<enum>. If C<*> is passed as
C<$count> an infinite L<Seq|/type/Seq> of C<Bool>s is returned.

    say Bool.roll;                                    # OUTPUT: «True␤»
    say Bool.roll(3);                                 # OUTPUT: «(True False False)␤»
    say Bool.roll(*);                                 # OUTPUT: «(...)␤»

=head2 routine Numeric

    multi method Numeric(Bool:D --> Int:D)

Returns the value part of the C<enum> pair.

    say False.Numeric;                                # OUTPUT: «0␤»
    say True.Numeric;                                 # OUTPUT: «1␤»

=head1 Operators

=head2 prefix ?

    multi sub prefix:<?>(Mu --> Bool:D)

Coerces its argument to C<Bool>.

=head2 prefix so

    multi sub prefix:<so>(Mu --> Bool:D)

Coerces its argument to C<Bool>, has looser precedence than C<< prefix:<?> >>.

=end pod

# vim: expandtab softtabstop=4 shiftwidth=4 ft=perl6
